<?php
/**
 * 数据库驱动接口
 *
 * @package util.db.drivers
 * @since 0.2
 */
interface IDbDriver {
	/**
	 * 构造器
	 *
	 * @param array $config 连接配置
	 * @since 0.2
	 */
	public function __construct(array $config);
	
	/**
	 * 取得数据表列表
	 *
	 * @return array
	 * @since 0.2
	 */
	public function tableList();
	
	/**
	 * 取得表的描述
	 *
	 * @param string $name 表名称
	 * @return array
	 * @since 0.2
	 */
	public function describeTable($name);
	
	/**
	 * 连接数据库
	 *
	 * @since 0.2
	 */
	public function connect();
	
	/**
	 * 关闭连接
	 *
	 * @since 0.2
	 */
	public function close();
	
	/**
	 * 预处理一个SQL
	 *
	 * @param string $sql 原始SQL
	 * @param array $params 参数
	 * @return IDbStatement
	 * @since 0.2
	 */
	public function prepare($sql, $params = array());
	
	/**
	 * 取得最后插入的ID
	 *
	 * @param string $name 可能需要的字段名称
	 * @return string
	 * @since 0.2
	 */
	public function lastInsertId($name = null);
	
	/**
	 * 开始事务
	 *
	 * @since 0.2
	 */
	public function beginTransaction();
	
	/**
	 * 提交事务
	 *
	 * @since 0.2
	 */
	public function commit();
	
	/**
	 * 回滚事务
	 *
	 * @since 0.2
	 */
	public function rollBack();
	
	/**
	 * 给SQL加入limit条件
	 *
	 * @param string $sql SQL
	 * @param integer $count 总数
	 * @param integer $offset 开始位置
	 * @return string
	 * @since 0.2
	 */
	public function limit($sql, $count, $offset = 0);
	
	/**
	 * 引住数据
	 *
	 * @param mixed $data 需要加引号的数据
	 * @return mixed
	 * @since 0.2
	 */
	public function quote($data);
	
	/**
	 * 引住关键字
	 *
	 * @param string $keyword 关键字
	 * @return string
	 * @since 0.2
	 */
	public function quoteKeyword($keyword);
	
	/**
	 * 执行一条语句，并返回影响的行数
	 *
	 * @param string $sql SQL
	 * @return integer
	 * @since 0.2
	 */
	public function exec($sql);
	
	/**
	 * 利用原生的方法/函数执行语句，并返回执行结果
	 *
	 * @param string $sql SQL
	 * @return mixed
	 * @since 0.2
	 */
	public function nativeExec($sql);
	
	/**
	 * 执行一条语句，返回预处理语句
	 *
	 * @param string $sql SQL
	 * @param integer $fetchType 返回方式，参见IDb::FETCH_*
	 * @return IDbStatment
	 * @since 0.2
	 */
	public function query($sql, $fetchType = IDb::FETCH_ASSOC);	
	
	/**
	 * 取得一行记录
	 *
	 * @param mixed $result nativeExec返回的结果集
	 * @param integer $fetchType 返回方式，参见IDb::FETCH_*
	 * @param integer $columnIndex 列序号，对于$fetchType为IDb::FETCH_COLUMN有效
	 * @since 0.2
	 */
	public function fetch($result, $fetchType = IDb::FETCH_BOTH, $columnIndex = 0);
	
	/**
	 * 取得所有记录
	 *
	 * @param mixed $result nativeExec返回的结果集
	 * @param integer $fetchType 返回方式，参见IDb::FETCH_*
	 * @param integer $columnIndex 列序号，对于$fetchType为IDb::FETCH_COLUMN有效
	 * @since 0.2
	 */
	public function fetchAll($result, $fetchType = IDb::FETCH_BOTH, $columnIndex = 0);
	
	/**
	 * 取得错误
	 *
	 * 返回格式为：
	 * array (
	 *   "code" => 1002,
	 * 	 "message" => "syntax error"
	 * )
	 * 
	 * 如果返回是一个空数组，意味着没有错误发生
	 * 
	 * @since array
	 * @since 0.2
	 */
	public function error();
	
	/**
	 * 取得影响的行数
	 *
	 * @param mixed $result nativeExec的结果集
	 * @since 0.2
	 */
	public function rowCount($result);
}

?>